package com.example.docmanagement.dto.request;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

/**
 * 文档查询请求 DTO
 * 用于分页查询、搜索和筛选文档列表
 * 
 * 示例URL查询参数:
 * /api/v1/documents?page=1&pageSize=20&categoryId=1&status=published&keyword=Java&tags=教程,入门&sortBy=viewCount&sortOrder=desc
 * 
 * 响应示例:
 * {
 * "success": true,
 * "data": {
 * "data": [...],
 * "page": 1,
 * "pageSize": 20,
 * "total": 100,
 * "totalPages": 5,
 * "hasNext": true,
 * "hasPrevious": false
 * }
 * }
 */
@Data
@Schema(description = "文档查询请求（支持分页、筛选、搜索、排序）")
public class DocumentQueryRequest {

    /**
     * 当前页码（可选）
     * 从1开始计数
     * 默认值：1
     * 示例：2（表示第二页）
     */
    @Schema(description = "当前页码", example = "1", defaultValue = "1", minimum = "1")
    private Integer page = 1;

    /**
     * 每页显示数量（可选）
     * 控制每页返回的文档数量
     * 默认值：10
     * 建议范围：1-100
     * 示例：20
     */
    @Schema(description = "每页显示数量", example = "10", defaultValue = "10", minimum = "1", maximum = "100")
    private Integer pageSize = 10;

    /**
     * 分类ID筛选（可选）
     * 只返回指定分类下的文档
     * 示例：1（只显示分类ID为1的文档）
     * 为空则不按分类筛选
     */
    @Schema(description = "分类ID筛选", example = "1")
    private Long categoryId;

    /**
     * 文档状态筛选（可选）
     * 只返回指定状态的文档
     * 可选值：
     * - "draft": 草稿
     * - "published": 已发布
     * - "archived": 已归档
     * 示例："published"（只显示已发布的文档）
     * 为空则返回所有状态的文档
     */
    @Schema(description = "文档状态筛选", example = "published", allowableValues = { "draft", "published", "archived" })
    private String status;

    /**
     * 搜索关键词（可选）
     * 在文档标题、摘要、内容中搜索包含该关键词的文档
     * 支持模糊匹配
     * 示例："Java教程"
     * 为空则不进行关键词搜索
     */
    @Schema(description = "搜索关键词（支持模糊匹配）", example = "Java教程")
    private String keyword;

    /**
     * 标签筛选（可选）
     * 多个标签用逗号分隔，返回包含任一标签的文档
     * 示例："java,教程,入门"
     * 为空则不按标签筛选
     */
    @Schema(description = "标签筛选（逗号分隔）", example = "java,教程,入门")
    private String tags;

    /**
     * 排序字段（可选）
     * 指定按哪个字段排序
     * 可选值：
     * - "createdAt": 创建时间（默认）
     * - "updatedAt": 更新时间
     * - "publishedAt": 发布时间
     * - "viewCount": 浏览量
     * - "likeCount": 点赞数
     * - "title": 标题（字母顺序）
     * 默认值："createdAt"
     */
    @Schema(description = "排序字段", example = "createdAt", allowableValues = { "createdAt", "updatedAt", "publishedAt",
            "viewCount", "likeCount", "title" }, defaultValue = "createdAt")
    private String sortBy = "createdAt";

    /**
     * 排序方向（可选）
     * 指定升序还是降序排列
     * 可选值：
     * - "asc": 升序（从小到大、从旧到新）
     * - "desc": 降序（从大到小、从新到旧，默认）
     * 默认值："desc"
     */
    @Schema(description = "排序方向", example = "desc", allowableValues = { "asc", "desc" }, defaultValue = "desc")
    private String sortOrder = "desc";
}
